MacWorld 1998 October/Macworld (1998-10).dmg/Shareware World/Utilities/Text Processing/GST-ShawBerry/ShawBerry - Read Me

Text File | 1998-08-01 | 11.0 KB | 251 lines | [TEXT/ttxt]

RELEASE NOTES FOR SHAWBERRY...



The usual white noise...

This software is named after Kip Shaw, for two very good reasons.
First, it was Kip who got me to do it now, rather than later. And,
second, I keep coming up with ideas for software I fully intend to
name after Kip, only to roll those ideas into other tools. I figured
I'd better get the job done now, rather than take the chance of
forgetting to do it later.

ShawBerry: Kip and his wife, Faiga, sent our children a load of
wonderful books. Among them was a volume called "Jamberry", by
Bruce Degan, which is great fun to declaim. From there it's not
hard to see how I arrived at this name.

We did this now because PixPex, if used in bulk, can create a very
time-consuming editing problem. We discussed a number of ways
around this, but none of them seemed fully satisfactory to me.
Moreover, none of the stop-gap solutions offered aid for other,
similar problems. So: ShawBerry will not only plug PixPexSpex lines
into a file, it will also deal with a host of other text merging
problems. For example: if you have a spreadsheet PRN file that
comes to you in chunks, you can reassemble the rows to the way they
appear within the spreadsheet. Problems such as these are not
terribly common - but they don't _need_ to be for this software to
save you a whale of a lot of time.

And: the lines are blurring in my work between quick hacks and
serious utilities. This is a serious piece of software, and yet I
knocked it out in a couple of hours at the end of a long and ugly
day. I'm even prouder of myself than normal (grin), and the pains
we've taken to make modeless an essentially modal function help
ShawBerry to live up to its honorable namesake.



ShawBerry: the nitty gritty details...

ShawBerry does this: it merges text from one file into another at
the insertion points you specify. You tell it which file to amend
and which file to take the amendments from. You can control whether
or not the insertion point text is retained or omitted, whether
searchable marks are inserted before and after the amendment text,
and whether or not the amendment is followed by a carriage return.

ShawBerry works by interaction _only._ I much prefer to work by
Drag & Drop, but I saw no fail-safe way for the software to
distinguish the Amend file from the Amendment file. Consequently,
you must specify each one interactively, by means of Standard File
dialogs.

When you hit the Start button, ShawBerry searches within the Amend
file until it finds the first instance of the Insertion point text.
It then "pastes" in the first line of Amendment text, inserting it
_before_ the Insertion point. The the same thing is done for the
second Insertion point found, pasting the second amendment, and so
on, until the Amend file is completed. A new file (BBEdit by
default) is written to disk using a name you specify.

ShawBerry works out of one modeless dialog box, plus the menu bar.
About and Quit are familiar to everyone. The Command key
equivalents for Copy, Paste, and Cut work.

In the Preferences menu, when you Save preferences, the switch
settings and the Insertion point text are saved. So if you have a
default way of working, save the whole thing as your prefs and they
will come up with each launch.

(Res Edit Hacks only: you can have two sets of prefs like this: set
up one set and Save, Quit, from ResEdit copy the contents of PREF 129
into PREF 128, launch ShawBerry and set up another set of prefs and
Save again (which, of course, overwrites PREF 129); now the first set
is available from Restore defaults, and the second comes up at launch
time and when you Restore saved prefs; this general procedure will
work with any app of mine that has a Preferences menu.)

At the top of the dialog box is a Text Edit region into which you
specify your Insertion point text. An Insertion point can be up to
254 characters in length. It consists of _string literals,_ that is
literal case-sensitive text characters with no wildcards. However,
two aliases are permitted: ^t (or ^T) to denote a Tab and ^p (or
^P) to denote a Carriage Return. An Insertion point is essentially
a search string, and it must reflect text actually present in the
Amend file. If it is absent, you will get an error message and
you'll have the opportunity to fix the mistake. The best way to
assure fault-free performance is to simply Copy the Insertion point
text from the Amend file and Paste it into ShawBerry.

The "Amend…" button presents a Standard File dialog that you will
use to specify the file into which you will be "pasting"
amendments.

The "Amendment…" button presents a Standard File dialog that you
will use to specify the file from which the amendments will be
"copied".

In other words: the Amend file is _almost_ the way you want it. The
Amendments file contains correction lines that, when "pasted" into
the Amend file, will fix it in the way that you want. Amendments
are written one to a paragraph. Ideally, there should be a
one-to-one correspondece between Insertion points in the Amend file
and amendment lines in the Amendment file. However: in the name of
modelessness, we are permitting you to proceed even if there are
more of one than the other. If there are extra Insertion points,
nothing will be pasted in. If there are extra amendments, they will
be appended in bulk at the end of the file ShawBerry creates.

Below the Amend button is a radio button group that controls how
the Insertion point text will be handled in the Amend file. If Omit
text is selected, the Insertion point text will be omitted from the
file ShawBerry creates. If Retain text is selected, the Insertion
point text will be output after the amendment, since amendments are
"pasted" in before the Insertion point. Below, we'll talk about how
to take advantage of this switch.

Below the Amendment button are two check boxes which control how
amendments are "pasted" in. If Insert marks is checked, searchable
marks will be inserted immediately before and after the amendment
text. The mark before the amendment is "|[|" (omitting the quote
marks), and the mark after is "|]|". Users of Torquemada's
wildstrings will not need to be told what to do about these, but
I'll be blathering about them later, anyway.

If Strip returns is checked, the trailing carriage return that ends
each amendment line is omitted from the file ShawBerry creates.
Since amendment lines must end in a carriage return, so that
ShawBerry can tell one from the next, we need a way to specify
whether the returns are to be included with the amendment, or if
they're simply there as terminators.

The Quit button is obvious - I hope! (grin)

The Start… button sets the ball in motion. An astounding amount of
error-trapping happens when you hit start, and each error condition
presents a modal dialog telling you what's gone wrong and giving
you a chance to fix it. If you get a message advising you that the
files are too large to fit in the current memory allocation, Quit
from ShawBerry and increase its allocation; ShawBerry will process
arbitrarily large files so long as it has memory enough to fit both
the Amend and Amendment files in RAM simultaneously.

Finally, ShawBerry is 32-bit clean, multi-finder friendly, Apple
Human Interface Guidelines loyal, System 6, 7 or 8 brave,
external-application courteous, and it possesses many other fine
qualities associated with Boy Scouts and software by me.
Incidentally, ShawBerry does _not_ feature the understated yet
strangely exotic Movado Museum watch cursor, since it's too damn
fast to need it. Also incidentally, ShawBerry makes use of
technology that will, someday, make it possible for Torquemada to
run without a watch cursor...



ShawBerry in real life...

I think it might be better if the universe were asequential...

I had to spew out all of the above static in order to get to this
static. The details above make no sense without this as context,
but this context would make no sense without the above details to
refer back to. So: either we rewrite the time functions to permit
optional randomization, or I'm going to have to get someone else to
write docs for me... (grin)

All right, look at it: here's Kip's problem: he has a file of text
that is flagged with text like this: "[PICTURE 1]", "[PICTURE 2]",
"[PICTURE 3]". He want to paste an Xtags picture box specification
in each of those spots. Surprise!: a PixPexSpex… file is a
perfectly formatted Amendment file, as is (assuming he clicked on
the pictures in the right order). So he could do two things:

1. Run a Torquemada set like this

[PICTURE ^#^?]
[PICTURE]

which makes the flags searchably consistent. Then he specifies
"[PICTURE]" as his Insertion point in ShawBerry, hits Omit text,
unchecks Insert marks and checks Strip returns, specifies the
Torqued file as his Amend file and the PixPexSpex… file as his
Amendment file. Presto! Done...

2. Alternatively, he could specify "[PICTURE " as his Insertion
point and run on the _original_ file, with Insert marks checked,
then Torque like this:

|[|^?|]|^*]
^?

to remove the marks and the leftover text.

That's what the marks are for, to make uniquely searchable
Torquemada strings. You can also use them in conjunction with your
word processor to make sure that what you got is what you wanted.

Here's more: in the TorqueManual, I talk about how to take text set
in multiple columns and break it up into one long column. Suppose
you want to do the opposite? Why? Life is like that sometimes. I've
has people send me PRN files from _very_ wide spreadsheet files.
The spreadsheet software would only permit PRN files to be ±140
characters wide, so the spreadsheets would be segmented in vertical
chunks, perfectly useless. I've also had parallel database reports
that needed to be merged into one horizontal line of data. And I've
had situations where lines from separate files needed to be blended
as alternating paragraphs. All of these are duck soup for
ShawBerry.

Take the spreadsheets (please!): the Amend file would be the left
chunk, the Amendment file the next chunk to the right (with the
procedure repeated for any additional chunks). The insertion point
is "^p", the end of the line, soldier. We'll Retain text and Strip
returns, although we could do just the opposite. Better the former
if we Insert marks, as we mght want to do in order to verify and
clean-up the formatting.

And the blended paragraphs: Insertion point is "^p", Retain text,
uncheck Strip returns. Voila!



Wave bye-bye...!

That's it, I think. This solves Kip's immediate problem in a way
that makes sense to me: I think both Kip and I are commited to
having all of the work done _before_ text is imported, so this
stands a fair chance of eliminating some delays from the process.
Moreover, it makes it possible to do generalized merging for any
data processing purpose. In conjunction with Torquemada, it makes a
formidable tool. Likewise for Shane the Plane. In the Shane the
Plane documentation, Kip has words for all of us on how to use
Shane, Caesura, Torquemada, ShawBerry and other stuff to achieve
some really impressive hands-off text massage...



Very Best,



Greg Swann

[e-mail]

3608 West Cochise Drive
Phoenix, AZ 85051

8/1/98